Inside Macintosh: More Macintosh Toolbox /: Chapter 7 - Translation Manager

Summary of Translation Extensions

This section provides Pascal, C, and assembly-language summaries for the constants, data types, and routines you can use to write a translation extension. For a summary of the constants, data types, and routines that applications can use, see "Summary of the Translation Manager" beginning on page 7-63.

Pascal Summary

Constants

CONST
   {component flags}
   kSupportsFileTranslation               = 1;  {file translation extension}
   kSupportsScrapTranslation              = 2;  {scrap translation extension}
   {translation attributes}
   taDstDocNeedsResourceFork              = 1;  {doc needs a resource fork}
   taDstIsAppTranslation                  = 2;  {app will translate doc}
   {request codes for translation extensions}
   kTranslateGetFileTranslationList       = 0;
   kTranslateIdentifyFile                 = 1;
   kTranslateTranslateFile                = 2;
   kTranslateGetScrapTranslationList      = 10;
   kTranslateIdentifyScrap                = 11;
   kTranslateTranslateScrap               = 12;

Data Types

TYPE
   FileType                = OSType;   {file types}
   ScrapType               = ResType;  {scrap types}
   TranslationAttributes   = LongInt;
   FileTypeSpec = 
   RECORD
      format:           FileType;
      hint:             LongInt;
      flags:            TranslationAttributes;
      catInfoType:      OSType;
      catInfoCreator:   OSType;
   END;
   FileTranslationList = 
   RECORD
      modDate:                LongInt;
      groupCount:             LongInt;
      {group1SrcCount:        LongInt;}
      {group1SrcEntrySize:    LongInt;}
      {group1SrcTypes:        ARRAY[1..group1SrcCount] OF FileTypeSpec;}
      {group1DstCount:        LongInt;}
      {group1DstEntrySize:    LongInt;}
      {group1DstTypes:        ARRAY[1..group1DstCount] OF FileTypeSpec;}
      {repeat above six lines for a total of groupCount times}
   END;
   FileTranslationListPtr     = ^FileTranslationList;
   FileTranslationListHandle  = ^FileTranslationListPtr;
   ScrapTypeSpec = 
   RECORD
      format:           ScrapType;
      hint:             LongInt;
   END;
   ScrapTranslationList = 
   RECORD
      modDate:                LongInt;
      groupCount:             LongInt;
      {group1SrcCount:        LongInt;}
      {group1SrcEntrySize:    LongInt;}
      {group1SrcTypes:        ARRAY[1..group1SrcCount] OF ScrapTypeSpec;}
      {group1DstCount:        LongInt;}
      {group1DstEntrySize:    LongInt;}
      {group1DstTypes:        ARRAY[1..group1DstCount] OF ScrapTypeSpec;}
      {repeat above six lines for a total of groupCount times}
   END;
   ScrapTranslationListPtr    = ^ScrapTranslationList;
   ScrapTranslationListHandle = ^ScrapTranslationListPtr;
   TranslationRefNum          = LongInt;

Translation Extension Routines

Managing Translation Progress Dialog Boxes

FUNCTION SetTranslationAdvertisement
                          (refNum: TranslationRefNum; 
                           advertisement: PicHandle): OSErr;
FUNCTION UpdateTranslationProgress
                          (refNum: TranslationRefNum; 
                           percentDone: Integer; 
                           VAR canceled: Boolean): OSErr;

Translation Extension-Defined Routines

File Translation Extension Routines

FUNCTION DoGetFileTranslationList
                          (self: ComponentInstance; 
                           translationList: FileTranslationListHandle)
                           : ComponentResult;
FUNCTION DoIdentifyFile   (self: ComponentInstance; 
                           theDoc: FSSpec; 
                           VAR docKind: FileType): ComponentResult;
FUNCTION DoTranslateFile  (self: ComponentInstance; 
                           refNum: TranslationRefNum; 
                           srcDoc: FSSpec; 
                           srcType: FileType; 
                           srcTypeHint: LongInt; 
                           dstDoc: FSSpec; 
                           dstType: FileType; 
                           dstTypeHint: LongInt): ComponentResult;

Scrap Translation Extension Routines

FUNCTION DoGetScrapTranslationList
                          (self: ComponentInstance;
                           list: ScrapTranslationListHandle)
                           : ComponentResult;
FUNCTION DoIdentifyScrap  (self: ComponentInstance;
                           dataPtr: Ptr;
                           dataLength: Size;
                           VAR dataFormat: ScrapType): ComponentResult;
FUNCTION DoTranslateScrap (self: ComponentInstance;
                           refNum: TranslationRefNum;
                           srcDataPtr: Ptr;
                           srcDataLength: Size;
                           srcType: ScrapType;
                           srcTypeHint: LongInt;
                           dstData: Handle;
                           dstType: ScrapType;
                           dstTypeHint: LongInt): ComponentResult;

C Summary

Constants

/*component flags*/
#define kSupportsFileTranslation          1  /*file translation extension*/
#define kSupportsScrapTranslation         2  /*scrap translation extension*/
/*translation attributes*/
#define taDstDocNeedsResourceFork         1  /*doc needs a resource fork*/
#define taDstIsAppTranslation             2  /*app will translate doc*/
/*request codes for translation extensions*/
enum {
   kTranslateGetFileTranslationList       = 0,
   kTranslateIdentifyFile,
   kTranslateTranslateFile,
   kTranslateGetScrapTranslationList      = 10,
   kTranslateIdentifyScrap,
   kTranslateTranslateScrap
};

Data Types

typedef OSType             FileType;               /*file types*/
typedef ResType            ScrapType;              /*scrap types*/
typedef unsigned long      TranslationAttributes;
struct FileTypeSpec {
   FileType                   format;
   long                       hint;
   TranslationAttributes      flags;      
   OSType                     catInfoType;
   OSType                     catInfoCreator;
}
typedef struct FileTypeSpec FileTypeSpec;
struct FileTranslationList {
   unsigned long              modDate;
   unsigned long              groupCount;
   /*unsigned long            group1SrcCount;*/
   /*unsigned long            group1SrcEntrySize;*/
   /*FileTypeSpec             group1SrcTypes[group1SrcCount];*/
   /*unsigned long            group1DstCount;*/
   /*unsigned long            group1DstEntrySize;*/
   /*FileTypeSpec             group1DstTypes[group1DstCount];*/
   /*repeat above six lines for a total of groupCount times*/
};
typedef struct FileTranslationList FileTranslationList;
typedef FileTranslationList   *FileTranslationListPtr, 
                              **FileTranslationListHandle;
struct ScrapTypeSpec {
   ScrapType                  format;
   long                       hint;
}
typedef struct ScrapTypeSpec ScrapTypeSpec;
struct ScrapTranslationList {
   unsigned long              modDate;
   unsigned long              groupCount;
   /*unsigned long            group1SrcCount;*/
   /*unsigned long            group1SrcEntrySize;*/
   /*ScrapTypeSpec            group1SrcTypes[group1SrcCount];*/
   /*unsigned long            group1DstCount;*/
   /*unsigned long            group1DstEntrySize;*/
   /*ScrapTypeSpec            group1DstTypes[group1DstCount];*/
   /*repeat above six lines for a total of groupCount times*/
};
typedef struct ScrapTranslationList ScrapTranslationList;
typedef ScrapTranslationList  *ScrapTranslationListPtr, 
                              **ScrapTranslationListHandle;
typedef long                  TranslationRefNum;

Translation Extension Routines

Managing Translation Progress Dialog Boxes

pascal OSErr SetTranslationAdvertisement
                        (TranslationRefNum refnum, 
                         PicHandle advertisement);
pascal OSErr UpdateTranslationProgress
                        (TranslationRefNum refnum,
                         short percentDone, 
                         Boolean* canceled);

Translation Extension-Defined Routines

File Translation Extension Routines

pascal ComponentResult DoGetFileTranslationList
                        (ComponentInstance self, 
                         FileTranslationListHandle translationList);
pascal ComponentResult DoIdentifyFile
                        (ComponentInstance self, 
                         const FSSpec* theDoc, 
                         FileType* docKind);
pascal ComponentResult DoTranslateFile
                        (ComponentInstance self, 
                         TranslationRefNum refNum, 
                         const FSSpec* srcDoc, 
                         FileType srcType, 
                         long srcTypeHint, 
                         const FSSpec* dstDoc, 
                         FileType dstType, 
                         long dstTypeHint);

Scrap Translation Extension Routines

pascal ComponentResult DoGetScrapTranslationList
                        (ComponentInstance self, 
                         ScrapTranslationListHandle list);
pascal ComponentResult DoIdentifyScrap
                        (ComponentInstance self, 
                         const void* dataPtr, 
                         Size dataLength, 
                         ScrapType* dataFormat);
pascal ComponentResult DoTranslateScrap
                        (ComponentInstance self, 
                         TranslationRefNum refNum, 
                         const void* srcDataPtr, 
                         Size srcDataLength, 
                         ScrapType srcType, 
                         long srcTypeHint, 
                         Handle dstData, 
                         ScrapType dstType, 
                         long dstTypeHint);

Assembly-Language Summary

Data Structures

File Type Specification
0 `format` 4 bytes the file type
4 hint 4 bytes reserved for use by your translation extension
8 flags 4 bytes flags for controlling translation
12 catInfoType 4 bytes the file's catalog type
16 catInfoCreator 4 bytes the file's catalog creator

File Translation List
0 `modDate` 4 bytes the creation date of the file translation list
4 groupCount 4 bytes the number of translation groups that follow

Scrap Type Specification
0 format 4 bytes the scrap type
4 hint 4 bytes reserved for use by your translation extension

Scrap Translation List
0 modDate 4 bytes the creation date of the scrap translation list
4 groupCount 4 bytes the number of translation groups that follow

Trap Macros

Trap Macros Requiring Routine Selectors

_TranslationDispatch

Selector	Routine
$0001	UpdateTranslationProgress
$0002	SetTranslationAdvertisement

Result Codes

noErr	0	No error
dskFulErr	-34	Not enough disk space to translate file
fnfErr	-43	Document not found
paramErr	-50	Parameter error
noTypeErr	-102	Unrecognized file or scrap type
memFullErr	-108	Not enough memory
dirNFErr	-120	Source or destination directory does not exist
wrgVolTypErr	-123	Volume does not support Desktop Manager
userCanceledErr	-128	The user canceled the translation
invalidTranslationPathErr	-3025	`srcType` to `dstType` is not a valid path
couldNotParseSourceFileErr	-3026	Source document is not of type `srcType`
afpItemNotFound	-5012	Could not determine kind string; or, application information not found

0	`format`	4 bytes	the file type
4	hint	4 bytes	reserved for use by your translation extension
8	flags	4 bytes	flags for controlling translation
12	catInfoType	4 bytes	the file's catalog type
16	catInfoCreator	4 bytes	the file's catalog creator

0	`modDate`	4 bytes	the creation date of the file translation list
4	groupCount	4 bytes	the number of translation groups that follow

0	format	4 bytes	the scrap type
4	hint	4 bytes	reserved for use by your translation extension

0	modDate	4 bytes	the creation date of the scrap translation list
4	groupCount	4 bytes	the number of translation groups that follow

Summary of Translation Extensions

Pascal Summary

Constants

Data Types

Translation Extension Routines

Managing Translation Progress Dialog Boxes

Translation Extension-Defined Routines

File Translation Extension Routines

Scrap Translation Extension Routines

C Summary

Constants

Data Types

Translation Extension Routines

Managing Translation Progress Dialog Boxes

Translation Extension-Defined Routines

File Translation Extension Routines

Scrap Translation Extension Routines

Assembly-Language Summary

Data Structures

File Type Specification 0format4 bytesthe file type 4hint4 bytesreserved for use by your translation extension 8flags4 bytesflags for controlling translation 12catInfoType4 bytesthe file's catalog type 16catInfoCreator4 bytesthe file's catalog creator

File Translation List 0modDate4 bytesthe creation date of the file translation list 4groupCount4 bytesthe number of translation groups that follow

Scrap Type Specification 0format4 bytesthe scrap type 4hint4 bytesreserved for use by your translation extension

Scrap Translation List 0modDate4 bytesthe creation date of the scrap translation list 4groupCount4 bytesthe number of translation groups that follow

Trap Macros

Trap Macros Requiring Routine Selectors

Result Codes

File Type Specification
0 `format` 4 bytes the file type
4 hint 4 bytes reserved for use by your translation extension
8 flags 4 bytes flags for controlling translation
12 catInfoType 4 bytes the file's catalog type
16 catInfoCreator 4 bytes the file's catalog creator

File Translation List
0 `modDate` 4 bytes the creation date of the file translation list
4 groupCount 4 bytes the number of translation groups that follow

Scrap Type Specification
0 format 4 bytes the scrap type
4 hint 4 bytes reserved for use by your translation extension

Scrap Translation List
0 modDate 4 bytes the creation date of the scrap translation list
4 groupCount 4 bytes the number of translation groups that follow